
<!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

    <title>Naming conventions and LAVA architecture &#8212; LAVA 2024.05 documentation</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css" />
    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/sphinx_highlight.js"></script>
    <link rel="shortcut icon" href="_static/favicon.ico"/>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="LAVA review criteria" href="review-criteria.html" />
    <link rel="prev" title="LAVA Software Community Project Contribution Guide" href="contribution.html" />
    <link rel="canonical" href="https://docs.lavasoftware.org/lava/naming-conventions.html" />
  
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
<script type="text/javascript" src="_static/js/jquery-1.12.4.min.js"></script>
<script type="text/javascript" src="_static/js/jquery-fix.js"></script>
<script type="text/javascript" src="_static/bootstrap-3.4.1/js/bootstrap.min.js"></script>
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>


  </head><body>

  <div id="navbar" class="navbar navbar-default navbar-fixed-top">
    <div class="container">
      <div class="navbar-header">
        <!-- .btn-navbar is used as the toggle for collapsed navbar content -->
        <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
        </button>
        <a class="navbar-brand" href="index.html"><span><img src="_static/lava.png"></span>
          LAVA</a>
        <span class="navbar-text navbar-version pull-left"><b>2024.05</b></span>
      </div>

        <div class="collapse navbar-collapse nav-collapse">
          <ul class="nav navbar-nav">
            
                <li><a href="genindex.html">Index</a></li>
                <li><a href="contents.html">Contents</a></li>
            
            
              <li class="dropdown globaltoc-container">
  <a role="button"
     id="dLabelGlobalToc"
     data-toggle="dropdown"
     data-target="#"
     href="index.html">Site <b class="caret"></b></a>
  <ul class="dropdown-menu globaltoc"
      role="menu"
      aria-labelledby="dLabelGlobalToc"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="index.html">Introduction to LAVA</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="contents.html">Contents</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary of terms</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="support.html">Getting support</a></li>
</ul>
</ul>
</li>
              
                <li class="dropdown">
  <a role="button"
     id="dLabelLocalToc"
     data-toggle="dropdown"
     data-target="#"
     href="#">Page <b class="caret"></b></a>
  <ul class="dropdown-menu localtoc"
      role="menu"
      aria-labelledby="dLabelLocalToc"><ul>
<li><a class="reference internal" href="#">Naming conventions and LAVA architecture</a></li>
</ul>
</ul>
</li>
              
            
            
              
                
  <li>
    <a href="contribution.html" title="Previous Chapter: LAVA Software Community Project Contribution Guide"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">&laquo; LAVA Software...</span>
    </a>
  </li>
  <li>
    <a href="review-criteria.html" title="Next Chapter: LAVA review criteria"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">LAVA review criteria &raquo;</span>
    </a>
  </li>
              
            
            
            
            
              <li class="hidden-sm"></li>
            
          </ul>

          
            
<form class="navbar-form navbar-right" action="search.html" method="get">
 <div class="form-group">
  <input type="text" name="q" class="form-control" placeholder="Search" />
 </div>
  <input type="hidden" name="check_keywords" value="yes" />
  <input type="hidden" name="area" value="default" />
</form>
          
        </div>
    </div>
  </div>

<div class="container">
  <div class="row">
    <div class="body col-md-12 content" role="main">
      
  <section id="naming-conventions-and-lava-architecture">
<span id="naming-conventions"></span><span id="index-0"></span><h1>Naming conventions and LAVA architecture<a class="headerlink" href="#naming-conventions-and-lava-architecture" title="Permalink to this heading">¶</a></h1>
<p>Certain terms used in LAVA have specific meanings. Please be
consistent in the use of the following terms:</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="glossary.html#glossary"><span class="std std-ref">Glossary of terms</span></a></p>
</div>
<dl>
<dt><strong>board</strong></dt><dd><p>The physical hardware sitting in a rack or on a desk. The difference
between a <em>board</em> and a <em>device</em> is that a board can be replaced if
it fails completely, yet the device remains unchanged in the database
and the replacement board can pick up running LAVA test jobs as soon
as the device is set back to “good health”. For example, a board can
suffer an electrical short or connectors being sheared off. A device
only changes state (Idle and Running) or health (Good, Bad,
Maintenance, Retired).</p>
<p>Integrating new types of board into LAVA can be a difficult and
protracted process. CI requires high levels of reliability from
boards, including when stressed at high load. Not all boards can be
integrated into LAVA.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="device-integration.html#adding-new-device-types"><span class="std std-ref">Adding new device types</span></a> and <a class="reference internal" href="glossary.html#term-health-check"><span class="xref std std-term">health check</span></a>.</p>
</div>
</dd>
<dt><strong>connection</strong></dt><dd><p>A means of communicating with a device. This will often involve
using a serial port, but can also be <a class="reference external" href="http://www.openssh.com/">SSH</a> or another way of obtaining
a shell-type interactive interface. Connections will typically
require a <a class="reference external" href="http://www.opengroup.org/austin/papers/posix_faq.html">POSIX</a> type shell.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="connections.html#connections"><span class="std std-ref">Connections</span></a></p>
</div>
</dd>
<dt><strong>device</strong></dt><dd><p>In <code class="docutils literal notranslate"><span class="pre">lava-server</span></code>, a <a class="reference internal" href="glossary.html#term-device"><span class="xref std std-term">device</span></a> is a database object in LAVA
which stores configuration, information and status relating to a
single board. The device information can be represented in export
formats like YAML for use when the database is not accessible.</p>
<p>In <code class="docutils literal notranslate"><span class="pre">lava-dispatcher</span></code>, the database is not accessible so the
scheduler prepares a simple dictionary of values derived from the
database and the template to provide the information about the
device.</p>
<p>Devices are typically expected to persist long enough to provide long
term comparative data, for example to support LTS teams.</p>
</dd>
<dt><strong>device tag</strong></dt><dd><p>If specified boards have peripherals added (USB flash storage, SATA,
HDMI etc.) then admins can choose to create a <a class="reference internal" href="glossary.html#term-device-tag"><span class="xref std std-term">device tag</span></a> so
that test writers can write test jobs which use those peripherals and
the scheduler will assign the device according to the required device
tags.</p>
<p>A device tag is not meant to be a method of running specific test
jobs on specific boards. LAVA is not a board farm and a board can be
replaced at any time without affecting ongoing CI. There is no
support in LAVA for allocating specific boards to specific test
jobs, the two models are incompatible.</p>
<p>Device tags frequently apply to multiple devices. This allows the
queue of test jobs to be optimized and get results back to the
developers as quickly as possible without compromising reliability.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="glossary.html#term-device-tag"><span class="xref std std-term">device tag</span></a></p>
</div>
</dd>
<dt><strong>device-type</strong></dt><dd><p>A database object which collates similar devices into a group for
purposes of scheduling. Devices of a single type are often the same
vendor model but not all boards of the same model will necessarily be
of the same <a class="reference internal" href="glossary.html#term-device-type"><span class="xref std std-term">device-type</span></a>.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="devicetypes.html#device-types"><span class="std std-ref">Device types</span></a></p>
</div>
</dd>
<dt><strong>dispatcher</strong></dt><dd><p>The dispatcher software relates to the <code class="docutils literal notranslate"><span class="pre">lava_dispatcher</span></code> module in
git and the <code class="docutils literal notranslate"><span class="pre">lava-dispatcher</span></code> binary package in Debian. The
dispatcher software for LAVA can be installed without the server or
the scheduler and a machine configured in this way is also called a
<a class="reference internal" href="glossary.html#term-dispatcher"><span class="xref std std-term">dispatcher</span></a>. Such machines are typically expensive, especially
in a busy instance, which can have a big impact on how a LAVA lab is
built.</p>
</dd>
<dt><strong>dynamic data</strong></dt><dd><p>The Action base class provides access to dynamic data stores which
other actions can access. This provides the way for action classes to
share information like temporary paths of downloaded and / or
modified files and other data which is generated or calculated during
the operation of the pipeline. Use <code class="docutils literal notranslate"><span class="pre">self.set_common_data</span></code> to set
the namespace, key and value and <code class="docutils literal notranslate"><span class="pre">self.get_common_data</span></code> to retrieve
the value using the namespace and the key.</p>
</dd>
<dt><strong>parameters</strong></dt><dd><p>A static, read-only, dictionary of values which are available for the job
and the device. <a class="reference internal" href="glossary.html#term-parameters"><span class="xref std std-term">Parameters</span></a> must not be modified
by the codebase - use the <code class="docutils literal notranslate"><span class="pre">common_data</span></code> primitives of the Action
base class to copy parameters and store the modified values as
dynamic data.</p>
</dd>
<dt><strong>pipeline</strong></dt><dd><p>The internal name for the design of LAVA V2, based on how the actions
to be executed by the dispatcher are arranged in a unidirectional
pipeline object. The contents of the pipe are validated before the
job starts and the description of all elements in the pipe is
retained for later reference.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="dispatcher-design.html#pipeline-construction"><span class="std std-ref">Pipeline construction and flow</span></a> and <a class="reference internal" href="glossary.html#term-pipeline"><span class="xref std std-term">pipeline</span></a> in the
Glossary.</p>
</div>
</dd>
<dt><strong>protocol</strong></dt><dd><p>An API used by the python code inside <code class="docutils literal notranslate"><span class="pre">lava_dispatcher</span></code> to interact
with external systems and daemons when a shell like environment is
not supported. <a class="reference internal" href="glossary.html#term-protocol"><span class="xref std std-term">Protocols</span></a> need to be supported
within the python codebase and currently include multinode, LXC and
vland.</p>
</dd>
<dt><strong>server software</strong></dt><dd><p>The server software relates to the <code class="docutils literal notranslate"><span class="pre">lava_server</span></code>,
<code class="docutils literal notranslate"><span class="pre">lava_scheduler_app</span></code> and <code class="docutils literal notranslate"><span class="pre">lava_results_app</span></code> source code in git
and the <code class="docutils literal notranslate"><span class="pre">lava-server</span></code> binary package in Debian. It includes LAVA
components covering the UI and the scheduler daemon.</p>
</dd>
<dt><strong>worker</strong></dt><dd><p>A daemon running on each dispatcher machine which communicates with
the lava-server-gunicorn using HTTP. The worker in LAVA uses whatever device
configuration the server provides. Commands in the device
configuration often use scripts and utilities which are only
installed on that dispatcher.</p>
<p>The objective of the worker is to run the specified jobs as reliably
as possible. Each worker spawns one process for each job, executing
the code in <code class="docutils literal notranslate"><span class="pre">lava_dispatcher</span></code>.</p>
</dd>
<dt><strong>test job</strong></dt><dd><p>A database object which is created for each submission and retains
the logs and pipeline information generated when the slave executes
the job on the device.</p>
<p>Test jobs are not intended to test devices or boards. Test jobs exist
to test software on multiple devices as part of continuous
development of software, e.g. the Linux kernel. Each test
job is used to test one software build using the first available
device of the requested device-type. LAVA is not best suited to
QA operations at the end of a production line.</p>
</dd>
<dt><strong>worker</strong></dt><dd><p>A database object providing a connection to a <strong>slave</strong> daemon on a
dispatcher. Each device must be assigned to a <a class="reference internal" href="glossary.html#term-worker"><span class="xref std std-term">worker</span></a> to run a
test job. One device can only be assigned to one worker at any one
time. A single dispatcher can operate more than one worker, typically
by hosting one or more slaves inside a docker container.</p>
<p>Admins need to balance the number of devices on each worker according
to the load caused when all devices on that worker are running test
jobs simultaneously.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>It is common to find that all devices on a worker could
be executing at high load at precisely the same time. For example,
decompressing downloaded files (causing high CPU load / RAM usage)
or writing large files (high I/O load). Some test jobs may also
cause high network load. Admins need to monitor and balance the
load on each worker according to the specific workload of each
instance.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="growing_your_lab.html#lab-scaling"><span class="std std-ref">How many devices is too many for one worker?</span></a>.</p>
</div>
</dd>
</dl>
</section>


    </div>
      
  </div>
</div>
<footer class="footer">
  <div class="container">
    <p class="pull-right">
      <a href="#">Back to top</a>
      
    </p>
    <p>
        &copy; Copyright 2010-2019, Linaro Limited.<br/>
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 5.3.0.<br/>
    </p>
  </div>
</footer>
  </body>
</html>